is
Type check values
For example, is.string('🦄') //=> true
Highlights
Install
$ npm install @sindresorhus/is
Usage
const is = require('@sindresorhus/is');
is('🦄');
is(new Map());
is.number(6);
Assertions perform the same type checks, but throw an error if the type does not match.
const {assert} = require('@sindresorhus/is');
assert.string(2);
And with TypeScript:
import {assert} from '@sindresorhus/is';
assert.string(foo);
API
is(value)
Returns the type of value
.
Primitives are lowercase and object types are camelcase.
Example:
'undefined'
'null'
'string'
'symbol'
'Array'
'Function'
'Object'
Note: It will throw an error if you try to feed it object-wrapped primitives, as that's a bad practice. For example new String('foo')
.
is.{method}
All the below methods accept a value and returns a boolean for whether the value is of the desired type.
Primitives
.undefined(value)
.null(value)
.string(value)
.number(value)
Note: is.number(NaN)
returns false
. This intentionally deviates from typeof
behavior to increase user-friendliness of is
type checks.
.boolean(value)
.symbol(value)
.bigint(value)
Built-in types
.array(value, assertion?)
Returns true if value
is an array and all of its items match the assertion (if provided).
is.array(value);
is.array(value, is.number);
.function(value)
.buffer(value)
.object(value)
Keep in mind that functions are objects too.
.numericString(value)
Returns true
for a string that represents a number satisfying is.number
, for example, '42'
and '-8.3'
.
Note: 'NaN'
returns false
, but 'Infinity'
and '-Infinity'
return true
.
.regExp(value)
.date(value)
.error(value)
.nativePromise(value)
.promise(value)
Returns true
for any object with a .then()
and .catch()
method. Prefer this one over .nativePromise()
as you usually want to allow userland promise implementations too.
.generator(value)
Returns true
for any object that implements its own .next()
and .throw()
methods and has a function definition for Symbol.iterator
.
.generatorFunction(value)
.asyncFunction(value)
Returns true
for any async
function that can be called with the await
operator.
is.asyncFunction(async () => {});
is.asyncFunction(() => {});
.asyncGenerator(value)
is.asyncGenerator(
(async function * () {
yield 4;
})()
);
is.asyncGenerator(
(function * () {
yield 4;
})()
);
.asyncGeneratorFunction(value)
is.asyncGeneratorFunction(async function * () {
yield 4;
});
is.asyncGeneratorFunction(function * () {
yield 4;
});
.boundFunction(value)
Returns true
for any bound
function.
is.boundFunction(() => {});
is.boundFunction(function () {}.bind(null));
is.boundFunction(function () {});
.map(value)
.set(value)
.weakMap(value)
.weakSet(value)
Typed arrays
.int8Array(value)
.uint8Array(value)
.uint8ClampedArray(value)
.int16Array(value)
.uint16Array(value)
.int32Array(value)
.uint32Array(value)
.float32Array(value)
.float64Array(value)
.bigInt64Array(value)
.bigUint64Array(value)
Structured data
.arrayBuffer(value)
.sharedArrayBuffer(value)
.dataView(value)
Emptiness
.emptyString(value)
Returns true
if the value is a string
and the .length
is 0.
.nonEmptyString(value)
Returns true
if the value is a string
and the .length
is more than 0.
.emptyStringOrWhitespace(value)
Returns true
if is.emptyString(value)
or if it's a string
that is all whitespace.
.emptyArray(value)
Returns true
if the value is an Array
and the .length
is 0.
.nonEmptyArray(value)
Returns true
if the value is an Array
and the .length
is more than 0.
.emptyObject(value)
Returns true
if the value is an Object
and Object.keys(value).length
is 0.
Please note that Object.keys
returns only own enumerable properties. Hence something like this can happen:
const object1 = {};
Object.defineProperty(object1, 'property1', {
value: 42,
writable: true,
enumerable: false,
configurable: true
});
is.emptyObject(object1);
.nonEmptyObject(value)
Returns true
if the value is an Object
and Object.keys(value).length
is more than 0.
.emptySet(value)
Returns true
if the value is a Set
and the .size
is 0.
.nonEmptySet(Value)
Returns true
if the value is a Set
and the .size
is more than 0.
.emptyMap(value)
Returns true
if the value is a Map
and the .size
is 0.
.nonEmptyMap(value)
Returns true
if the value is a Map
and the .size
is more than 0.
Miscellaneous
.directInstanceOf(value, class)
Returns true
if value
is a direct instance of class
.
is.directInstanceOf(new Error(), Error);
class UnicornError extends Error {}
is.directInstanceOf(new UnicornError(), Error);
.urlInstance(value)
Returns true
if value
is an instance of the URL
class.
const url = new URL('https://example.com');
is.urlInstance(url);
.urlString(value)
Returns true
if value
is a URL string.
Note: this only does basic checking using the URL
class constructor.
const url = 'https://example.com';
is.urlString(url);
is.urlString(new URL(url));
.truthy(value)
Returns true
for all values that evaluate to true in a boolean context:
is.truthy('🦄');
is.truthy(undefined);
.falsy(value)
Returns true
if value
is one of: false
, 0
, ''
, null
, undefined
, NaN
.
.nan(value)
.nullOrUndefined(value)
.primitive(value)
JavaScript primitives are as follows: null
, undefined
, string
, number
, boolean
, symbol
.
.integer(value)
.safeInteger(value)
Returns true
if value
is a safe integer.
.plainObject(value)
An object is plain if it's created by either {}
, new Object()
, or Object.create(null)
.
.iterable(value)
.asyncIterable(value)
.class(value)
Returns true
for instances created by a class.
.typedArray(value)
.arrayLike(value)
A value
is array-like if it is not a function and has a value.length
that is a safe integer greater than or equal to 0.
is.arrayLike(document.forms);
function foo() {
is.arrayLike(arguments);
}
foo();
.inRange(value, range)
Check if value
(number) is in the given range
. The range is an array of two values, lower bound and upper bound, in no specific order.
is.inRange(3, [0, 5]);
is.inRange(3, [5, 0]);
is.inRange(0, [-2, 2]);
.inRange(value, upperBound)
Check if value
(number) is in the range of 0
to upperBound
.
is.inRange(3, 10);
.domElement(value)
Returns true
if value
is a DOM Element.
.nodeStream(value)
Returns true
if value
is a Node.js stream.
const fs = require('fs');
is.nodeStream(fs.createReadStream('unicorn.png'));
.observable(value)
Returns true
if value
is an Observable
.
const {Observable} = require('rxjs');
is.observable(new Observable());
.infinite(value)
Check if value
is Infinity
or -Infinity
.
.evenInteger(value)
Returns true
if value
is an even integer.
.oddInteger(value)
Returns true
if value
is an odd integer.
.any(predicate | predicate[], ...values)
Using a single predicate
argument, returns true
if any of the input values
returns true in the predicate
:
is.any(is.string, {}, true, '🦄');
is.any(is.boolean, 'unicorns', [], new Map());
Using an array of predicate[]
, returns true
if any of the input values
returns true for any of the predicates
provided in an array:
is.any([is.string, is.number], {}, true, '🦄');
is.any([is.boolean, is.number], 'unicorns', [], new Map());
.all(predicate, ...values)
Returns true
if all of the input values
returns true in the predicate
:
is.all(is.object, {}, new Map(), new Set());
is.all(is.string, '🦄', [], 'unicorns');
Type guards
When using is
together with TypeScript, type guards are being used extensively to infer the correct type inside if-else statements.
import is from '@sindresorhus/is';
const padLeft = (value: string, padding: string | number) => {
if (is.number(padding)) {
return Array(padding + 1).join(' ') + value;
}
if (is.string(padding)) {
return padding + value;
}
throw new TypeError(`Expected 'padding' to be of type 'string' or 'number', got '${is(padding)}'.`);
}
padLeft('🦄', 3);
padLeft('🦄', '🌈');
Type assertions
The type guards are also available as type assertions, which throw an error for unexpected types. It is a convenient one-line version of the often repetitive "if-not-expected-type-throw" pattern.
import {assert} from '@sindresorhus/is';
const handleMovieRatingApiResponse = (response: unknown) => {
assert.plainObject(response);
assert.number(response.rating);
assert.string(response.title);
return `${response.title} (${response.rating * 10})`;
};
handleMovieRatingApiResponse({rating: 0.87, title: 'The Matrix'});
handleMovieRatingApiResponse({rating: '🦄'});
Generic type parameters
The type guards and type assertions are aware of generic type parameters, such as Promise<T>
and Map<Key, Value>
. The default is unknown
for most cases, since is
cannot check them at runtime. If the generic type is known at compile-time, either implicitly (inferred) or explicitly (provided), is
propagates the type so it can be used later.
Use generic type parameters with caution. They are only checked by the TypeScript compiler, and not checked by is
at runtime. This can lead to unexpected behavior, where the generic type is assumed at compile-time, but actually is something completely different at runtime. It is best to use unknown
(default) and type-check the value of the generic type parameter at runtime with is
or assert
.
import {assert} from '@sindresorhus/is';
async function badNumberAssumption(input: unknown) {
assert.promise<number>(input);
const resolved = await input;
return 2 * resolved;
}
async function goodNumberAssertion(input: unknown) {
assert.promise(input);
const resolved = await input;
assert.number(resolved);
return 2 * resolved;
}
badNumberAssumption(Promise.resolve('An unexpected string'));
goodNumberAssertion(Promise.resolve('An unexpected string'));
FAQ
Why yet another type checking module?
There are hundreds of type checking modules on npm, unfortunately, I couldn't find any that fit my needs:
- Includes both type methods and ability to get the type
- Types of primitives returned as lowercase and object types as camelcase
- Covers all built-ins
- Unsurprising behavior
- Well-maintained
- Comprehensive test suite
For the ones I found, pick 3 of these.
The most common mistakes I noticed in these modules was using instanceof
for type checking, forgetting that functions are objects, and omitting symbol
as a primitive.
For enterprise
Available as part of the Tidelift Subscription.
The maintainers of @sindresorhus/is and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.
Related
Maintainers